<html>
<head>
<title>TFM</title>
<link rel="stylesheet" type="text/css" href="../../avisynth.css">
<!--
Automatically generated, don't change:
$Id: tivtc_tfm.htm,v 1.1 2005/07/10 16:11:01 wilbertd Exp $ 
-->
</head>
<body>
<h1>TFM</h1>
<h2>Abstract</h2>
<b>author:</b>    tritical
<br><b>version:</b>        0.9.8.1<br>
<b>download:</b>   <a href="http://bengal.missouri.edu/~kes25c/">http://bengal.missouri.edu/~kes25c/</a>
<br><b>category:</b>    Deinterlacing &amp; Pulldown Removal
<br><b>requirements:</b>&nbsp;
<ul>
  <li>YV12 &amp; YUY2 Colorspace</li>
</ul>

<p><b>license:</b> GPL</p>

<hr size=2 width="100%" align=center>

<!-- #EndTemplate -->
<h2>Table of Contents
</h2>
<ul>
  <li><a href="#general">    A.) General Info</a></li>
  <li><a href="#basic">B.) Basic Parameters</a></li>
  <li><a href="#advanced">C.) Advanced Parameters</a></li>
  <li><a href="#io-par">D.) File Input/Output Parameters</a></li>
  <li><a href="#debug">E.) Debug/Display Parameters</a></li>
  <li><a href="#overrides">F.) Overrides Info</a></li>
  <li><a href="#overrides">G.) Changelist</a></li>
</ul>
<h2><a name="general"></a>A.)  GENERAL INFO:
</h2>
<p>TFM is a field matching filter that recovers the original progressive frames from a   telecined stream.  It does not decimate the resulting duplicate frames though, so to   achieve an ivtc you must follow TFM with a decimation filter such as TDecimate(), which
is also included in the tivtc.dll.
</p>
<h3>syntax
</h3>
<p>TFM (clip, int <var>&quot;order&quot;</var>, int <var>&quot;field&quot;</var>, int
<var>&quot;mode&quot;</var>, int <var>&quot;PP&quot;</var>. string <var>&quot;ovr&quot;</var>, string
<var>&quot;input&quot;</var>, string <var>&quot;output&quot;</var>,            string
<var>&quot;outputC&quot;</var>, bool <var>&quot;debug&quot;</var>, bool <var>&quot;display&quot;</var>, bool
<var>&quot;slow&quot;</var>, bool <var>&quot;mChroma&quot;</var>, int <var>&quot;cNum&quot;</var>,            int
<var>&quot;cthresh&quot;</var>, int <var>&quot;MI&quot;</var>, bool <var>&quot;chroma&quot;</var>, int
<var>&quot;blockx&quot;</var>, int <var>&quot;blocky&quot;</var>, int <var>&quot;y0&quot;</var>, int
<var>&quot;y1&quot;</var>,            int <var>&quot;mthresh&quot;</var>, PClip <var>&quot;clip2&quot;</var>, string
<var>&quot;d2v&quot;</var>, int <var>&quot;ovrDefault&quot;</var>)
</p>
<p>While TFM does have quite a few parameters, I have tried to categorize the settings so
they are easier to manage.  Really there are only 3 parameters most users should be
concerned about knowing or ever setting.  They are "order", "mode", and "PP" and are   described under the "BASIC PARAMETERS" sections.  The other settings are described under   the other various sections which should be pretty easy to figure out from the names.
</p>
<h2><a name="basic"></a>B.)  BASIC PARAMETERS:
</h2>
<p>These are the only three parameters most users should be concerned worth or worry about   setting.  They control the basic operation of the filter.
</p>
<p><var>order</var> -&nbsp;
</p>
<p>        Sets the field order of the clip. The field order must be correctly set for
accurate field matching to occur. Possible values:
</p>
<p>-1 = auto (use avisynth's internal parity value)<br>
            0 = bottom field first (bff)<br>
            1 = top field first (tff)
</p>
<p>Default:  -1  (int)
</p>
<p><var>mode</var> -&nbsp;
</p>
<p>        Sets the matching mode or strategy to use.  Plain 2-way matching (option 0) is the        safest of all the options in the sense that it wont risk creating jerkiness due to
duplicate frames when possible, but if there are bad edits or blended fields it will        end up outputting combed frames when a good match might actually exist.  3-way matching
+ trying the 4th/5th matches if all 3 of the original matches are detected as combed        (option 5) is the most risky in terms of creating jerkiness, but will almost always        find a good frame if there is one.  The other settings (options 1, 2, 3, and 4) are all        somewhere in between options 0 and 5 in terms of risking jerkiness and creating        duplicate frames vs. finding good matches in sections with bad edits, orphaned fields,        blended fields, etc... Possible settings are:
</p>
<p>0 = 2-way match                                                          (p/c)<br>
            1 = 2-way match + 3rd match on combed                                    (p/c + n)<br>
            2 = 2-way match + 3rd match (same order) on combed                       (p/c + u)<br>
            3 = 2-way match + 3rd match on combed + 4th/5th matches if still combed  (p/c + n + u/b)<br>
            4 = 3-way match                                                          (p/c/n)<br>
            5 = 3-way match + 4th/5th matches on combed                              (p/c/n + u/b)
</p>
<p>The () at the end indicate the matches that would be used for that mode assuming order = 1
and field = 1.
</p>
<p>* In terms of speed option 0 is by far the fastest and 5 is the slowest.
</p>
<p>Default:  1  (int)
</p>
<p><var>PP</var> -
</p>
<p>Sets the post-processing mode.  This controls how TFM should handle (or not handle)
any combed frames that come out of the field matching process.  Possible options
are:
</p>
<p>0 - nothing (don't even look for combed frames)<br>
            1 - find/hint combed frames but don't deinterlace<br>
            2 - dumb blend deinterlacing<br>
            3 - dumb cubic interpolation deinterlacing<br>
            4 - dumb modified-ela deinterlacing<br>
            5 - motion-adaptive blend deinterlacing<br>
            6 - motion-adaptive cubic interpolation deinterlacing<br>
            7 - motion-adaptive modified-ela deinterlacing
</p>
<p>* You can also use the "clip2" parameter to specify an externally deinterlaced clip
from which TFM will take frames instead of doing the deinterlacing itself.  See the clip2 parameter description for more info and to see how the PP settings effect
operation with clip2.
</p>
<p>* You can manually control what frames should be marked as combed as well as the
PP option through an overrides file (see the ovr parameter description)
</p>
<p>Default:  6  (int)
</p>
<h2><a name="advanced"></a>C.)  ADVANCED PARAMETERS:
</h2>
<p>These parameters give finer control over the matching operation, combed frame detection,
and deinterlacing of combed frames.  While correctly tweaking these values can increase<br>
   matching accuracy they can also make things worse if just changed randomly.
</p>
<p><var>field</var> -&nbsp;
</p>
<p>         Sets the field to match from.  It is recommended to set this to the same value
as order unless you experience matching failures with that setting.  In certain         circumstances changing the field that is used to match from can have a large impact         on matching performance. Possible values are:
</p>
<p>-1 = auto (TFM will set field to the same value as the order parameter)<br>
            0 = bottom field<br>
            1 = top field
</p>
<p>Default:  -1  (int)
</p>
<p><var>slow</var> -
</p>
<p>Sets whether or not the slower matching function or the faster matching function
is used.  The slower version is usually more accurate, but as the name says is slower.  This is basically a quality vs. speed option.
</p>
<p>true = slower version is used<br>
            false = faster version is used
</p>
<p>Default:  true  (bool)
</p>
<p><var>mChroma</var> -
</p>
<p>Sets whether or not chroma is included during the match comparisons.  In most
cases it is recommended to leave this enabled.  Only if your clip has bad chroma
problems such as heavy rainbowing or other artifacts should you set this to false.
Setting this to false could also be used to speed things up at the cost of some         accuracy.
</p>
<p>true = chroma is included<br>
            false = chroma is not included
</p>
<p>Default:  true  (bool)
</p>
<p><var>y0</var>/<var>y1</var> -
</p>
<p>These define an exclusion band which excludes the lines between y0 and y1 from
being included in the field matching decision.  An exclusion band can be used to ignore subtitles, a logo, or other things that may interfer with the matching.
y0 sets the starting scan line and y1 sets the ending line, all lines in between
y0 and y1 (including y0 and y1) will be ignored.  Set y0 equal to y1 to disable.
</p>
<p>Default:  y0 - 0  (int)<br>
                   y1 - 0  (int)
</p>
<p>The rest of the "advanced parameters" control combed frame detection and deinterlacing,   and are only used if mode is set to 1, 2, or 4 or PP (post-processing) is set to 1 or greater!
</p>
<p><var>cthresh</var> -
</p>
<p>This is the area combing threshold used for combed frame detection.  It is like         dthresh or dthreshold in telecide() and fielddeinterlace().  This essentially         controls how "strong" or "visible" combing must be to be detected.  Larger values
mean combing must be more visible and smaller values mean combing can be less visible or strong and still be detected.  Valid settings are from -1 (every pixel
will be detected as combed) to 255 (no pixel will be detected as combed).  This is bascially a pixel difference value.  A good range is between 8 to 12.
</p>
<p>Default:  10  (int)
</p>
<p><var>chroma</var> -
</p>
<p>Sets whether or not chroma is considered in the combed frame decision.  Only disable this if your source has chroma problems (rainbowing, etc...) that are
causing problems for the combed frame detection with chroma enabled.
</p>
<p>true = chroma is included<br>
            false = chroma is not included
</p>
<p>Default:  false  (bool)
</p>
<p><var>blockx</var> -
</p>
<p>Sets the x-axis size of the window used during combed frame detection.  This has
to do with the size of the area in which MI number of pixels are required to be detected as combed for a frame to be declared combed.  See the MI parameter
description for more info.  Possible values are any number that is a power of 2 starting at 4 and going to 2048 (i.e. 4, 8, 16, 32, ... 2048).
</p>
<p>Default:  16  (int)
</p>
<p><var>blocky</var> -
</p>
<p>Sets the y-axis size of the window used during combed frame detection.  This has
to do with the size of the area in which MI number of pixels are required to be detected as combed for a frame to be declared combed.  See the MI parameter
description for more info.  Possible values are any number that is a power of 2 starting at 4 and going to 2048 (i.e. 4, 8, 16, 32, ... 2048).
</p>
<p>Default:  16  (int)
</p>
<p><var>MI</var> -<br>
<br>
         The # of combed pixels inside any of the blocky by blockx size blocks on the frame         for the frame to be detected as combed. While cthresh controls how "visible" the
combing must be, this setting controls "how much" combing there must be in any localized         area (a window defined by the blockx and blocky settings) on the frame.  Min setting = 0,         max setting = blocky x blockx (at which point no frames will ever be detected as combed).
</p>
<p>Default:  85  (int)
</p>
<p><var>mthresh</var> -&nbsp;<br>
<br>
         Sets the motion (pixel difference) threshold for deinterlacing when using motion
adaptation (PP > 4).  As said, it is simply a pixel difference threshold between
frames... if under mthresh then a pixel is considered static, if over mthresh it is
considered moving.
</p>
<p>Default:  5  (int)
</p>
<p><var>clip2</var> -
</p>
<p>When using PP > 1 this parameter may be used to specify a clip to take deinterlaced         frames from instead of using one of TFM's inbuilt deinterlacing methods.  If PP &lt; 5         then frames will be taken as is from clip2, if PP >= 5 (i.e. using motion adaptation)         then TFM will build the mask as usual and only pixels in moving areas will be taken         from the frames in clip2. Don't specify anything for clip2 to use TFM's internal         deinterlacing.  For an example of using clip2 see the clip2_sample_avs.avs file.
</p>
<p>Default:  NULL  (PClip)
</p>
<h2><a name="io-par"></a>D.)  FILE INPUT/OUTPUT PARAMETERS:
</h2>
<p>These settings deal with overrides file usage and output/input file options.
</p>
<p><var>d2v</var> -&nbsp;
</p>
<p>        This option is intended to be used if you are using an mpeg2source() with a d2v file.
It sets the name and path to a d2v file, which TFM will analyze to see if there are any
illegal field order changes and optionally set the order parameter using the field
order of the d2v file.  If the d2v file is found to have illegal field order transitions,
TFM will create a fixed d2v file with the string "-FIXED" attached to the end of the file
name.  The new file will be located in the same directory as the original.  You can then
use this fixed d2v file for processing.  If the order parameter is set to "-1" then TFM
will detect the field order from the d2v file and set the order parameter to match.  TFM
will also pass info from the d2v on to tdecimate to help aid duplicate detection and hybrid
detection.
</p>
<p>*NOTE:  This option currently supports all d2v formats that I am aware of... which
include:  dvd2avi 1.76, 1.77.3 and its variants, all dvd2avidg versions, and                    all dgindex versions.
</p>
<p>example =>  TFM(d2v="myd2v.d2v")
</p>
<p>Default:  ""  (String)
</p>
<p><var>ovr</var> -<br>
<br>
        Sets the name and path to an overrides file.  An overrides file allows for manual control
over what matches are used for specific frames and ranges of frames, for changing the        values of the field, mode, order, mthresh, and PP parameters for specific frames or ranges        of frames, and for specifiying whether or not a frame should be consider combed or not        combed.  For more information on using an overrides file see the OVERRIDES section at the        bottom of this file.  You can specify an ovr file and an input file at the same time.        Matches and combed frames given in the overrides file will take precedence over those in        the input file.
</p>
<p>example =>   TFM(ovr="myOvrFile.txt")
</p>
<p>* NOTE:  The ovr option CANNOT read output files (files made via the output option).
To read output files use the input parameter.
</p>
<p>Default:  ""  (String)
</p>
<p><var>ovrDefault</var> -
</p>
<p>This is an extra option that allows you to change the default "combed" action taken when        using an ovr file.  By default, if you don't specify a frame as combed '+' or not combed '-'
in an overrides file then TFM just processes it as usual.  However, with the ovrDefault
option, you can make TFM mark all frames you don't explicitly specify as either combed
or not combed.  Basically, its an easy way to only deinterlace a few specific frames in
a file and make sure no other frames are touched or vice versa.  If no ovr file is
used then this setting does nothing.  Possible settings:
</p>
<p>0 - normal processing<br>
              1 - mark all frames not specified in ovr file as clean (not combed)<br>
              2 - mark all frames not specified in ovr file as combed
</p>
<p>Default:  0  (int)
</p>
<p><var>output</var> -&nbsp;
</p>
<p>        Sets the name and path for an output file.  TFM will create the specified file and        output all the matches and combed frame decisions used to it.  Each line will contain        a frame number, the match used, and the combed frame decision used.  This file        can then be used later for input via the input parameter (so that the matches wont        have to be recalculated).
</p>
<p>Default:  ""  (String)
</p>
<p><var>input</var> -
</p>
<p>This option is meant to be used with the output option.  If you have used the output
option on a previous pass then to reuse that info set the input parameter to the name
and path of the output file.  You can specify both an input file and an ovr file at        the same time.  In such a case, matches in the overrides file will take precedence.        The input option CANNOT read ovr files!!!  To read an ovr file you must use the ovr
parameter!
</p>
<p>Default:  ""  (String)
</p>
<p><var>outputC</var> -
</p>
<p>This option can be used to help identify 30fps progressive video sections by outputting
the ranges over which at least "cNum" of consecutive matches were matched as 'c'.  This
option isn't fool proof, as slow or static film scenes can also generate long series of        consecutive 'c' matches.
</p>
<p>Default:  ""  (String)
</p>
<p><var>cNum</var> -
</p>
<p>Number of consecutive 'c' matches required to output a range when using the outputC
option.
</p>
<p>Default:  15  (int)
</p>
<h2><a name="debug"></a>E.)  DEBUG/DISPLAY PARAMETERS:
</h2>
<p>These settings control whether debug information is output or if display information   is drawn on the frames.  These options can be useful when using overrides or when trying
to assess matching failures.
</p>
<p><var>debug</var> -
</p>
<p>If set to true, information will be output via OutputDebugString() during processing concerning TFM's internal operations.  Info includes: match
comparision statistics, match used, what matches were detected as combed (if in modes 1, 2, or 4 or PP > 0), and the values of field, mode, order, and MIC.
To view this information you can use a utility called "DebugView" available for free from:&nbsp;
</p>
<p><a href="http://www.sysinternals.com/ntw2k/freeware/debugview.shtml">                http://www.sysinternals.com/ntw2k/freeware/debugview.shtml</a>
</p>
<p>true = enables output<br>
            false = disables output
</p>
<p>Default:  false  (bool)
</p>
<p><var>display</var> -<br>
<br>
         If set to true, information will be drawn on the video frames themselves
in the upper left hand corner.  This info is not as detailed as the debug output and only includes the current frame number, the values of mode,
field, order, and MIC the match that was used for the current frame, and whether
or not the output frame was combed if PP > 0.  This option can be useful when using overrides and you need to see what match is currently
being used. If you need more detailed information, such as the match statistic numbers
or to see if specific matches were detected as combed then you'll need to         use debug output.  As of v0.9.1 display will also indicate if the final         output frame is combed and whether or not it was
deinterlaced if PP > 0. If PP = 1 and display is enabled, then TFM will draw a white box around the         area of the frame that triggered its detection as combed when a frame is         found to be combed through its internal detection (this wont be done if a         frame is forced to be combed through overrides).
</p>
<p>true = enables<br>
            false = disables
</p>
<p>Default:  false  (bool)
</p>
<h2><a name="overrides"></a>F.)  OVERRIDES:
</h2>
<p>This section gives an explanation of how to specify overrides, what each type of
match means, and the list of possible overrides.
</p>
<h3>BACKGROUND AND OVERVIEW:
</h3>
<p>Before we get started there is one thing that needs to be understood, and that is
what in the hell the p, c, n, b, and u letters mean and where they come from ;)&nbsp;
Well, actually, before that we need to know what field matching actually does.  I     am going to assume that the reader knows what is meant by saying a stream is     telecined though.  Now, consider we have the following telecined stream with the     bottom and top fields given as follows (1t and 1b are both assumed to come from     the same progressive frame, as are 2t and 2b, etc...):
</p>
<table border="1" width="40%">
  <tr>
    <td width="5%" align="center">1t</td>
    <td width="5%" align="center">2t</td>
    <td width="5%" align="center">3t</td>
    <td width="5%" align="center">4t</td>
    <td width="5%" align="center">5t</td>
    <td width="20%">  &lt;= original stream</td>
  </tr>
  <tr>
    <td width="5%" align="center">1b</td>
    <td width="5%" align="center">2b</td>
    <td width="5%" align="center">3b</td>
    <td width="5%" align="center">4b</td>
    <td width="5%" align="center">5b</td>
    <td width="20%">&nbsp;</td>
  </tr>
</table>
<p>Now what TFM does, as does any field matcher, is matches the fields so that only
progressive frames remain; however, it does not decimate duplicates.  So, the above
input stream gets transformed into one of the two following scenarios (which one     depends on the field we are matching from, i.e. the value of the "field" parameter):
</p>
<p>field = 0  (matching from bottom)
</p>
<table border="1" width="40%">
  <tr>
    <td width="5%" align="center">1t</td>
    <td width="5%" align="center">2t</td>
    <td width="5%" align="center">3t</td>
    <td width="5%" align="center">4t</td>
    <td width="5%" align="center">4t</td>
    <td width="20%">  &lt;= output stream</td>
  </tr>
  <tr>
    <td width="5%" align="center">1b</td>
    <td width="5%" align="center">2b</td>
    <td width="5%" align="center">3b</td>
    <td width="5%" align="center">4b</td>
    <td width="5%" align="center">4b</td>
    <td width="20%">&nbsp;</td>
  </tr>
  <tr>
    <td width="5%" align="center">c</td>
    <td width="5%" align="center">c</td>
    <td width="5%" align="center">n</td>
    <td width="5%" align="center">n</td>
    <td width="5%" align="center">c</td>
    <td width="20%">   &lt;= matches used</td>
  </tr>
</table>
<p>field = 1  (matching from top)
</p>
<table border="1" width="40%">
  <tr>
    <td width="5%" align="center">1t</td>
    <td width="5%" align="center">2t</td>
    <td width="5%" align="center">2t</td>
    <td width="5%" align="center">3t</td>
    <td width="5%" align="center">4t</td>
    <td width="20%">  &lt;= output stream</td>
  </tr>
  <tr>
    <td width="5%" align="center">1b</td>
    <td width="5%" align="center">2b</td>
    <td width="5%" align="center">2b</td>
    <td width="5%" align="center">3b</td>
    <td width="5%" align="center">4b</td>
    <td width="20%">&nbsp;</td>
  </tr>
  <tr>
    <td width="5%" align="center">c</td>
    <td width="5%" align="center">c</td>
    <td width="5%" align="center">p</td>
    <td width="5%" align="center">p</td>
    <td width="5%" align="center">c</td>
    <td width="20%">&lt;= matches used</td>
  </tr>
</table>
<p>From this example, you can see why the field setting can have an impact on the      matching performance...  Anyways, now that we have an idea of what is happening
we can move on to what p, c, n, b, and u mean.  Basically, these letters just stand
for what match is used.  As you can see from the above example, c means that the      field from the current frame and of the opposite parity to that of the field being      matched from is used, p means the field of the opposite parity to the field we are      matching from and from the previous frame is used, and n means the field of the      opposite parity and from the next frame is used.  These three matches, p, c, and n      are the most common or the usual matches.  In the mode parameter description these
are the three matches that make up the 2-way and 3-way matching.  The other matches:      u and b  are slightly different in that they don't use the field that is being matched      from.  In the mode parameter description these two matches are the 4th/5th matches.      A visual explanation of all of this would probably explain things much better, so here&nbsp;<br>
      are the visual representations of each match:
</p>
<p>* In the following examples it is assumed that we are currently matching              the second frame (2t/2b).  Also, an "x" has been placed next to both the              top field and the bottom field that will be used due to the current match.
</p>
<p>field = 0:
</p>
<table border="1" width="90%">
  <tr>
    <td width="15%" align="center">c</td>
    <td width="15%" align="center">p</td>
    <td width="15%" align="center">n</td>
    <td width="15%" align="center">b</td>
    <td width="15%" align="center">u</td>
    <td width="15%">  &lt;= match</td>
  </tr>
  <tr>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">x</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">x</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">x</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">x</td>
        </tr>
      </table>
    </td>
    <td width="15%">&lt;= stream</td>
  </tr>
  <tr>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">1t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" rowspan="2">&lt;= output frame</td>
  </tr>
  <tr>
    <td width="15%" align="center">2b</td>
    <td width="15%" align="center">2b</td>
    <td width="15%" align="center">2b</td>
    <td width="15%" align="center">1b</td>
    <td width="15%" align="center">3b</td>
  </tr>
</table>
<p>field = 1:
</p>
<table border="1" width="90%">
  <tr>
    <td width="15%" align="center">c</td>
    <td width="15%" align="center">p</td>
    <td width="15%" align="center">n</td>
    <td width="15%" align="center">b</td>
    <td width="15%" align="center">u</td>
    <td width="15%">  &lt;= match</td>
  </tr>
  <tr>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">x</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">x</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">x</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">
      <table border="1" width="100%">
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">&nbsp;</td>
          <td width="34%" align="center">x</td>
        </tr>
        <tr>
          <td width="33%" align="center">1t</td>
          <td width="33%" align="center">2t</td>
          <td width="34%" align="center">2t</td>
        </tr>
        <tr>
          <td width="33%" align="center">1b</td>
          <td width="33%" align="center">2b</td>
          <td width="34%" align="center">3b</td>
        </tr>
        <tr>
          <td width="33%" align="center">&nbsp;</td>
          <td width="33%" align="center">x</td>
          <td width="34%" align="center">&nbsp;</td>
        </tr>
      </table>
    </td>
    <td width="15%">&lt;= stream</td>
  </tr>
  <tr>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" align="center">1t</td>
    <td width="15%" align="center">2t</td>
    <td width="15%" rowspan="2">&lt;= output frame</td>
  </tr>
  <tr>
    <td width="15%" align="center">2b</td>
    <td width="15%" align="center">1b</td>
    <td width="15%" align="center">3b</td>
    <td width="15%" align="center">2b</td>
    <td width="15%" align="center">2b</td>
  </tr>
</table>
<p>Well, that should pretty well do it. There are a couple other points though. One, you can see from the above examples that the matches have different meanings
depending on the value of the "field" parameter.  That is why in all ovr files      you can specify the field value with respect to which the matches in the file are      made.  This is so that when you specify an n, p, etc... match in an ovr file, TFM      knows for sure what you mean.  You don't HAVE to specify the reference field though,
if you don't give one TFM simply assumes you mean to use the same value as the current internal field value.   However, it is much safer to specify the value.      The second point stems from the first point, and is simply that if the reference      field you use for an ovr file is different from that of the internal field value      then the matches will be switched accordingly so everything is the same.  However,      this means that if your using debug or display output the matches wont be the same      as the ones in your ovr file.  So for reference here are the conversions or      equivalencies...
</p>
<p>with Field = 0 ___ is the same as ___ with Field = 1 and vice versa:
</p>
<p>p == b<br>
c == c<br>
                             n        ==        u<br>
                             b        ==        p<br>
                             u        ==        n
</p>
<h3>SYNTAX AND USING OVERRIDES:
</h3>
<h4>match codes:
</h4>
<p>* See background/overview section for visual representation of matches. For range of frames overrides you can specify multiple match codes&nbsp;
on the same line and the given pattern will be repeated over the length of the range.
</p>
<p>p = match to previous field<br>
         c = match to current field<br>
         n = match to next field&nbsp;<br>
         b = match to previous field  (matches from opposite parity field)<br>
         u = match to next field      (matches from opposite parity field)
</p>
<h4>combed frame codes:
</h4>
<p>* These can be used to manually force specific frames to be consider combed or
clean.  You can specify patterns of combed frame codes like you can with               match codes.
</p>
<p>+ = force frame to be considered combed<br>
         - = force frame to be considered not combed&nbsp;
</p>
<h4>      parameter codes:
</h4>
<p>* Parameter codes, unlike match codes, also require a value to change to when used in overrides file.
</p>
<p>f = field<br>
         o = order<br>
         m = mode<br>
         M = mthresh<br>
         P = PP
</p>
<h4>reference field:
</h4>
<p>Since the match codes take on different meanings depending on the field parameter, you
can specify a reference field for an overrides file.  All the matches given in file         are then taken to be with respect to the given field.  If a reference field is not
given then all matches are taken to be with reference to the filters internal field         value.
</p>
<p>To specify the reference field you must put one of the following two lines as the
VERY FIRST active line in the file:
</p>
<p>field = top&nbsp;<br>
              field = bottom
</p>
<p>The first one would set the reference field to top (1) and the second would set it to
bottom (0).  For an example see the included example ovr file included in the filter         zip file.
</p>
<h4>override syntax:
</h4>
<p>single frame =>  frame_number code(s) [change_value]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[] = only required for parameter codes<br>
frame range =>   start_frame,end_frame code(s) [change_value]
</p>
<h4>examples:
</h4>
<p>0,100 pcpcbuu       will repeat the given pattern "pcpcbuu" of matches starting at                                  frame 0 and ending at frame 100
</p>
<table border="1" width="60%">
  <tr>
    <td width="20%">           101 p</td>
    <td width="50%">               will use match p for frame 101</td>
  </tr>
  <tr>
    <td width="20%">           300,400 c</td>
    <td width="50%">           will use match c for frames 300 through 400</td>
  </tr>
  <tr>
    <td width="20%">           100,150 f -1</td>
    <td width="50%">        will set the field parameter to -1 for frames 100 through 150</td>
  </tr>
  <tr>
    <td width="20%">           500,750 m 1</td>
    <td width="50%">         will set the mode parameter to 1 for frames 500 through 750</td>
  </tr>
  <tr>
    <td width="20%">           871 o 1</td>
    <td width="50%">             will set the order parameter to 1 (tff) for frame 871</td>
  </tr>
  <tr>
    <td width="20%">           3000,4231 cccpp</td>
    <td width="50%">     will repeat the cccpp pattern from frame 3000 till frame 4231</td>
  </tr>
  <tr>
    <td width="20%">           4343 u</td>
    <td width="50%">              will use match u for frame 4343</td>
  </tr>
  <tr>
    <td width="20%">           ;756 p</td>
    <td width="50%">              will be ignored</td>
  </tr>
  <tr>
    <td width="20%">           #what is this?!?!</td>
    <td width="50%">   will be ignored</td>
  </tr>
  <tr>
    <td width="20%">           70 -</td>
    <td width="50%">                will force frame 70 to be considered clean (not combed)</td>
  </tr>
  <tr>
    <td width="20%">           60,80 +</td>
    <td width="50%">             will force frames 60 through 80 to be considered combed</td>
  </tr>
  <tr>
    <td width="20%">           70,97 +--++</td>
    <td width="50%">         will force frames 70 to 97 to be considered combed or not combed                                  as indicated by the pattern given</td>
  </tr>
  <tr>
    <td width="20%">           87,100 P 2</td>
    <td width="50%">          will set the PP parameter to 2 for frames 87 through 100</td>
  </tr>
  <tr>
    <td width="20%">           200 M -1</td>
    <td width="50%">            will set the mthresh parameter to -1 for frame 200</td>
  </tr>
</table>
<h4>other things to know/remember:
</h4>
<p>1.) Ranges are inclusive.
</p>
<p>2.) For parameter codes, the changed value is always set back to what it was               originally set to after the override goes out of the specified range.               (i.e. if you specify a field override for frame 600 to 700 after frame               700 field is set back to its original value automatically, you don't need               to set it back in the overrides file!  The original value is what it is               set to on load (i.e. either the default or what you set it to in your               avisynth script).
</p>
<p>3.) Frame numbers must be within range for the file.
</p>
<p>4.) Frame numbers for match codes must be ascending, and frame numbers for the               same parameter codes must not overlap!!!  In other words, don't make               multiple overrides for the same parameter over the same range of frames.
</p>
<p>5.) The spacing is important!  (no spaces between the comma and frame numbers,               one space between the end frame number and the specifier, one space between               the specifier and the value to change to if it has one). Just look at the               examples for clarification.
</p>
<p>6.) Only match codes and combed frame codes can be used in pattern specifications.               Pattern specifications can be up to 50 match codes maximum.
</p>
<p>7.) To comment out a line (have TFM ignore it) in an ovr file, you can               either put a '#' symbol or ';' at the beginning of the line.
</p>
<p>8.) An example ovr file w/ comments is included in the filter zip file for reference.
</p>
<p>9.) Setting the second frame in a range to 0 means the same as setting it to the               last frame of the clip.
</p>
<h2><a name="changelist"></a>G.) Changelist
</h2>
<p>06/25/2005  v0.9.8.1<br>
+ Added support for new dgindex d2v's (d2vformat v10)
</p>
<p>06/06/2005  v0.9.8<br>
+ Added a new match mode (mode 2, old mode 2 is now mode 3, 3 is 4, and so on)<br>
         + Added support for new dgindex d2v's (d2vformat v9)
</p>
<p>04/20/2005  v0.9.7.3<br>
+ Debug and display options now output a value called MIC (the value that is computed              and compared against MI to check if a frame is combed) to make tweaking              the MI parameter easier.  The MIC value is computed during combed frame detection and              is the single highest value computed for any one of the blockx by blocky sized blocks.              Previously, combed frame detection exited immediately upon finding the first block              with an MIC value greater then MI... it now scans all blocks and returns the highest.
Thus, the white box that is drawn when display=true, PP=1, and a frame is detected
as combed now corresponds to the block with the highest MIC value and not the first&nbsp;
to be found.<br>
         - Changed default MI value to 85 (also changed to 85 in IsCombedTIVTC)<br>
         - Fixed the white box drawn on combed frames when PP=1 sometimes being drawn in the
incorrect spot when mode was set to 1, 2, or 4
</p>
<p>03/13/2005  v0.9.7.2<br>
+ Post-processing now only links luma->chroma on the motion map, instead of doing full
luma->chroma, chroma->luma, and chroma->chroma linking.
</p>
<p>03/10/2005  v0.9.7.1<br>
- Fixed a crash that would occur if the d2v option was enabled and a trim() or some other
filter that altered the number of frames was used prior to tfm().
</p>
<p>02/19/2005  v0.9.7<br>
+ Added support for new dgindex project file versions 07 and 08 (dgindex v1.2) to the d2v option.<br>
         - Fixed the d2v method of fixing illegal transitions.<br>
         + TFM now uses the rff flags from the d2v to help tdecimate identify duplicates and 24p film.<br>
         - Changed default MI value to 100.<br>
         - Fixed the readme file indicating chroma=true, when it actually defaults to false.
</p>
<p>01/08/2005  v0.9.6.3<br>
- Fixed SetCacheHints being called incorrectly and always defaulting to CACHE_ALL.
</p>
<p>01/02/2005  v0.9.6.2<br>
- Changed the d2v method of fixing illegal transitions to one that doesn't alter
the total # of fields in the clip or the # of fields from each of the original frames in the stream.<br>
         - Changed default value for the chroma option to false.<br>
         + Some other optimizations and internal changes.
</p>
<p>12/22/2004  v0.9.6.1<br>
         - Fixed passing AsClip() a NULL argument during TFM and TFMPP object creation if no clip
was given for clip2.  This would cause assertion failure when compiled in debug mode.
</p>
<p>12/19/2004  v0.9.6<br>
         - Fixed not invoking a cache between TFM and TFMPP when PP > 4.<br>
         + Some internal additions to allow TDecimate to tell the difference between c matches
and deinterlaced frames.<br>
         + Added debug output to d2v checking... when debug=true and a d2v file is specified it will
report the type of d2v detected, the detected field order from the d2v if order = -1,<br>
               and report the errors if any are found.
</p>
<p>11/30/2004  v0.9.4
</p>
<p>+ significant speed up (30-50%) to modes 1, 2, and 4 with PP > 0, due to some missing logic
the output frame would needlessly get checked twice for combing.
</p>
<p>11/28/2004  v0.9.3.1<br>
         - Fixed crashing when mode = 0 or mode = 3 and PP was greater then 0, the conditions
for an array allocation were not adjusted as needed when the PP option was added in v0.9.1.
</p>
<p>11/28/2004  v0.9.3<br>
+ Added crc checking to input/output files.  Whenever an output file is created, TFM creates a crc32 value based off the first 15 frames in
the current clip.  When the file is loaded via the "input" option the crc value from the file is checked against the current clips crc              value.
</p>
<p>11/27/2004  v0.9.2<br>
         - Fixed "slow" and "mChroma" parameters defaulting to false instead of true.<br>
         - Fixed display option not writing any part of a line if the total line
length exceeded the width of the frame instead of writing what would fit.<br>
         - Changed default cthresh value to 10.<br>
         - Changed default PP value to 6 (motion-adaptive cubic interpolation).<br>
         + Added d2v and ovrDefault options.<br>
         + Added IsCombedIVTC() conditional function.<br>
         + Added cubic deinterlacing method.<br>
         + Re-did input/output parameters.  Files created via the output option can
no longer be read via the ovr option!  You must use the input parameter to read files created via the output parameter!.<br>
         + Output option no longer requires linear access.
</p>
<p>11/21/2004  v0.9.1<br>
         - Changed default mode value to 1.<br>
         - Changed default MI value to 128.<br>
         - Allow blockx and blocky sizes up to 2048.<br>
         - Reordered the parameter syntax slightly.<br>
         + Added exclusion band (y0/y1).<br>
         + Added post-processing (PP parameter) and related stuff.<br>
             - Added clip2 and mthresh parameters.<br>
         + Added hinting in preparation for tdecimate.
</p>
<p>11/11/2004  v0.9.0<br>
         - initial release
</p>
<p><kbd>$Date: 2005/07/10 16:11:01 $</kbd>
</p>
</body>
</html>
